﻿/**
 * @file std_comm.h
 * Copyright (c) 2019 Gaaagaa. All rights reserved.
 * 
 * @author  : Gaaagaa
 * @date    : 2019-09-09
 * @version : 1.0.0.0
 * @brief   : declare for common data/macro/constants types.
 */

/**
 * The MIT License (MIT)
 * Copyright (c) Gaaagaa. All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is furnished to do
 * so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef __STD_COMM_H__
#define __STD_COMM_H__

////////////////////////////////////////////////////////////////////////////////

#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus

////////////////////////////////////////////////////////////////////////////////

#ifndef __XSTD_TYPES_64__
    #if (defined(_WIN32) || defined(_WIN64))
        #ifdef _WIN64
            #define __XSTD_TYPES_64__ 1
        #else // !_WIN64
            #define __XSTD_TYPES_64__ 0
        #endif // _WIN64
    #elif (defined(__linux__) || defined(__unix__))
        #ifdef __x86_64__
            #define __XSTD_TYPES_64__ 1
        #elif __i386__
            #define __XSTD_TYPES_64__ 0
        #else // unknow
            #error "unknow platform!"
        #endif // __x86_64__
    #else // UNKNOW
        #define __XSTD_TYPES_64__ 1
    #endif // PLATFORM
#endif // __XSTD_TYPES_64__

////////////////////////////////////////////////////////////////////////////////

typedef char                   xstd_char_t;
typedef unsigned char          xstd_uchar_t;

typedef char                   xstd_int8_t;
typedef short                  xstd_int16_t;
typedef int                    xstd_int32_t;
typedef long long              xstd_int64_t;

typedef unsigned char          xstd_uint8_t;
typedef unsigned short         xstd_uint16_t;
typedef unsigned int           xstd_uint32_t;
typedef unsigned long long     xstd_uint64_t;

typedef long                   xstd_long_t;
typedef long long              xstd_llong_t;
typedef unsigned long          xstd_ulong_t;
typedef unsigned long long     xstd_ullong_t;

typedef float                  xstd_float_t;
typedef double                 xstd_double_t;
typedef long double            xstd_ldouble_t;

typedef void                   xstd_void_t;
typedef unsigned char          xstd_byte_t;
typedef unsigned int           xstd_bool_t;
typedef unsigned char *        xstd_bptr_t;
typedef void *                 xstd_handle_t;
typedef void *                 xstd_owner_t;
typedef void *                 xstd_mptr_t;
typedef void *                 xstd_elem_t;

#if __XSTD_TYPES_64__
typedef xstd_int64_t           xstd_ssize_t;
typedef xstd_uint64_t          xstd_size_t;
#else // !__XSTD_TYPES_64__
typedef xstd_int32_t           xstd_ssize_t;
typedef xstd_uint32_t          xstd_size_t;
#endif // __XSTD_TYPES_64__

#define XSTD_FALSE             0
#define XSTD_TRUE              1
#define XSTD_NULL              0

#define XSTD_NAN_2PN           ((xstd_size_t)(8 * sizeof(xstd_size_t)))
#define XSTD_MAX_2POW          ((((xstd_size_t)~0) >> 1) + 1)

////////////////////////////////////////////////////////////////////////////////

typedef const struct xstd_context_t *   xstd_ctxt_t;

/**
 * @brief 执行内存块分配的回调函数类型。
 */
typedef xstd_mptr_t (* xstd_func_allocate_t)(xstd_size_t xst_size);

/**
 * @brief 执行内存块释放的回调函数类型。
 */
typedef xstd_void_t (* xstd_func_dealloc_t)(xstd_mptr_t xmt_mptr);

/**
 * @brief 节点存储的元素对象 的 拷贝构造操作 的回调函数类型。
 * 
 * @param [out] xet_dptr : 目标存储的元素对象。
 * @param [in ] xet_sptr : 源数据的元素对象。
 * @param [in ] xet_ctxt : 节点元素的上下文信息。
 */
typedef xstd_void_t (* xstd_func_copyctor_t)(
                            xstd_elem_t xet_dptr,
                            xstd_elem_t xet_sptr,
                            xstd_ctxt_t xet_ctxt);

/**
 * @brief 节点存储的元素对象 的 析构操作 的回调函数类型。
 * 
 * @param [out] xet_elem : 节点存储的元素对象。
 * @param [in ] xet_ctxt : 节点元素的上下文信息。
 */
typedef xstd_void_t (* xstd_func_destruct_t)(
                            xstd_elem_t xet_elem,
                            xstd_ctxt_t xet_ctxt);

/**
 * @brief 
 * 对两个 元素对象 进行比较操作（“小于”、“等于”、“大于” 等）的回调函数类型。
 * 
 * @param [in ] xet_lptr : 比较操作的左值元素对象。
 * @param [in ] xet_rptr : 比较操作的右值元素对象。
 * @param [in ] xet_ctxt : 节点元素的上下文信息。
 * 
 * @return xstd_bool_t : 比较结果。
 */
typedef xstd_bool_t (* xstd_func_compare_t)(
                            xstd_elem_t xet_lptr,
                            xstd_elem_t xet_rptr,
                            xstd_ctxt_t xet_ctxt);

/**
 * @brief 确认（条件判断）节点存储的元素对象 满足指定条件 的回调函数类型。
 * 
 * @param [in ] xet_vptr : 节点存储的元素对象。
 * @param [in ] xet_ctxt : 节点元素的上下文信息。
 * 
 * @return xstd_bool_t : 条件确认结果。
 */
typedef xstd_bool_t (* xstd_func_confirm_t)(
                            xstd_elem_t xet_vptr,
                            xstd_ctxt_t xet_ctxt);

/**
 * @brief 计算节点存储的元素对象 散列键值 的回调函数类型。
 * 
 * @param [in ] xet_vptr : 节点存储的元素对象。
 * @param [in ] xet_ctxt : 节点元素的上下文信息。
 * 
 * @return xstd_size_t : 散列值。
 */
typedef xstd_size_t (* xstd_func_hash_t)(
                            xstd_elem_t xet_vptr,
                            xstd_ctxt_t xet_ctxt);

//====================================================================

/**
 * @struct xstd_allocator_t
 * @brief  内存管理 相关操作接口 的结构体描述信息。
 */
typedef struct xstd_allocator_t
{
    xstd_func_allocate_t xfunc_allocate;  ///< 执行内存块分配的回调函数
    xstd_func_dealloc_t  xfunc_dealloc;   ///< 执行内存块释放的回调函数
    xstd_func_copyctor_t xfunc_copyfrom;  ///< 执行节点对象拷贝构造的回调函数
    xstd_func_copyctor_t xfunc_copymove;  ///< 执行节点对象右值 move 拷贝构造的回调函数
    xstd_func_destruct_t xfunc_destruct;  ///< 执行节点对象析构的回调函数
} xstd_allocator_t, * xstd_altor_t;

/** 声明通用的内存管理对象 */
extern const xstd_allocator_t xstd_altor_comm;

//====================================================================

/**
 * @enum  xstd_base_etype_t
 * @brief 存储基础数据类型的 节点类型标识 相关枚举值。
 */
typedef enum xstd_base_etype_t
{
    XSTD_ETYPE_CHAR    = 0x00000001,   ///< xstd_char_t
    XSTD_ETYPE_UCHAR   = 0x00000002,   ///< xstd_uchar_t
    XSTD_ETYPE_INT8    = 0x00000003,   ///< xstd_int8_t
    XSTD_ETYPE_INT16   = 0x00000004,   ///< xstd_int16_t
    XSTD_ETYPE_INT32   = 0x00000005,   ///< xstd_int32_t
    XSTD_ETYPE_INT64   = 0x00000006,   ///< xstd_int64_t
    XSTD_ETYPE_UINT8   = 0x00000007,   ///< xstd_uint8_t
    XSTD_ETYPE_UINT16  = 0x00000008,   ///< xstd_uint16_t
    XSTD_ETYPE_UINT32  = 0x00000009,   ///< xstd_uint32_t
    XSTD_ETYPE_UINT64  = 0x0000000A,   ///< xstd_uint64_t
    XSTD_ETYPE_LONG    = 0x0000000B,   ///< xstd_long_t
    XSTD_ETYPE_LLONG   = 0x0000000C,   ///< xstd_llong_t
    XSTD_ETYPE_ULONG   = 0x0000000D,   ///< xstd_ulong_t
    XSTD_ETYPE_ULLONG  = 0x0000000E,   ///< xstd_ullong_t
    XSTD_ETYPE_FLOAT   = 0x0000000F,   ///< xstd_float_t
    XSTD_ETYPE_DOUBLE  = 0x00000010,   ///< xstd_double_t
    XSTD_ETYPE_LDOUBLE = 0x00000011,   ///< xstd_ldouble_t

    XSTD_ETYPE_HANDLE  = 0x00000101,   ///< xstd_handle_t : 句柄

    XSTD_ETYPE_USER    = 0x00001000,   ///< 用户自定义的容器节点类型，应从此值开始递增
} xstd_base_etype_t;

/**
 * @struct xstd_context_t
 * @brief  容器所存节点的上下文信息描述的结构体。
 */
typedef struct xstd_context_t
{
    xstd_size_t   xstd_etype;  ///< 类型标识（参看 xstd_base_etype_t 枚举值，也可自行定义）
    xstd_size_t   xstd_esize;  ///< 节点缓存大小
    xstd_owner_t  xstd_owner;  ///< 所隶属的容器对象
    xstd_altor_t  xstd_altor;  ///< 内存管理器对象（注意，该对象，其生存期必须大于关联的 容器对象）
} xstd_context_t;

extern const xstd_context_t xstd_ctxt_char   ;  ///< 对应 xstd_char_t    类型
extern const xstd_context_t xstd_ctxt_uchar  ;  ///< 对应 xstd_uchar_t   类型
extern const xstd_context_t xstd_ctxt_int8   ;  ///< 对应 xstd_int8_t    类型
extern const xstd_context_t xstd_ctxt_int16  ;  ///< 对应 xstd_int16_t   类型
extern const xstd_context_t xstd_ctxt_int32  ;  ///< 对应 xstd_int32_t   类型
extern const xstd_context_t xstd_ctxt_int64  ;  ///< 对应 xstd_int64_t   类型
extern const xstd_context_t xstd_ctxt_uint8  ;  ///< 对应 xstd_uint8_t   类型
extern const xstd_context_t xstd_ctxt_uint16 ;  ///< 对应 xstd_uint16_t  类型
extern const xstd_context_t xstd_ctxt_uint32 ;  ///< 对应 xstd_uint32_t  类型
extern const xstd_context_t xstd_ctxt_uint64 ;  ///< 对应 xstd_uint64_t  类型
extern const xstd_context_t xstd_ctxt_long   ;  ///< 对应 xstd_long_t    类型
extern const xstd_context_t xstd_ctxt_llong  ;  ///< 对应 xstd_llong_t   类型
extern const xstd_context_t xstd_ctxt_ulong  ;  ///< 对应 xstd_ulong_t   类型
extern const xstd_context_t xstd_ctxt_ullong ;  ///< 对应 xstd_ullong_t  类型
extern const xstd_context_t xstd_ctxt_float  ;  ///< 对应 xstd_float_t   类型
extern const xstd_context_t xstd_ctxt_double ;  ///< 对应 xstd_double_t  类型
extern const xstd_context_t xstd_ctxt_ldouble;  ///< 对应 xstd_ldouble_t 类型
extern const xstd_context_t xstd_ctxt_handle ;  ///< 对应 xstd_handle_t  类型

//====================================================================

/**
 * @struct xstd_compare_t
 * @brief  节点存储元素的各类比较操作函数表。
 */
typedef struct xstd_compare_t
{
    xstd_func_compare_t  xfunc_eq;    ///< operator ==
    xstd_func_compare_t  xfunc_lt;    ///< operator <
    xstd_func_compare_t  xfunc_le;    ///< operator <=
    xstd_func_compare_t  xfunc_gt;    ///< operator >
    xstd_func_compare_t  xfunc_ge;    ///< operator >=
} xstd_compare_t;

extern const xstd_compare_t xstd_fcmp_comm   ;  ///< （使用内存模式的）通用类型的比较操作函数表
extern const xstd_compare_t xstd_fcmp_char   ;  ///< 对应 xstd_char_t    类型
extern const xstd_compare_t xstd_fcmp_uchar  ;  ///< 对应 xstd_uchar_t   类型
extern const xstd_compare_t xstd_fcmp_int8   ;  ///< 对应 xstd_int8_t    类型
extern const xstd_compare_t xstd_fcmp_int16  ;  ///< 对应 xstd_int16_t   类型
extern const xstd_compare_t xstd_fcmp_int32  ;  ///< 对应 xstd_int32_t   类型
extern const xstd_compare_t xstd_fcmp_int64  ;  ///< 对应 xstd_int64_t   类型
extern const xstd_compare_t xstd_fcmp_uint8  ;  ///< 对应 xstd_uint8_t   类型
extern const xstd_compare_t xstd_fcmp_uint16 ;  ///< 对应 xstd_uint16_t  类型
extern const xstd_compare_t xstd_fcmp_uint32 ;  ///< 对应 xstd_uint32_t  类型
extern const xstd_compare_t xstd_fcmp_uint64 ;  ///< 对应 xstd_uint64_t  类型
extern const xstd_compare_t xstd_fcmp_long   ;  ///< 对应 xstd_long_t    类型
extern const xstd_compare_t xstd_fcmp_llong  ;  ///< 对应 xstd_llong_t   类型
extern const xstd_compare_t xstd_fcmp_ulong  ;  ///< 对应 xstd_ulong_t   类型
extern const xstd_compare_t xstd_fcmp_ullong ;  ///< 对应 xstd_ullong_t  类型
extern const xstd_compare_t xstd_fcmp_float  ;  ///< 对应 xstd_float_t   类型
extern const xstd_compare_t xstd_fcmp_double ;  ///< 对应 xstd_double_t  类型
extern const xstd_compare_t xstd_fcmp_ldouble;  ///< 对应 xstd_ldouble_t 类型
extern const xstd_compare_t xstd_fcmp_handle ;  ///< 对应 xstd_handle_t  类型

////////////////////////////////////////////////////////////////////////////////

/**********************************************************/
/**
 * @brief 
 * 开启 通用内存管理 的记录工作流程。
 * @note 
 * 返回的句柄，后续可按 xstd_mdebug_t 对象的操作接口获取其他信息。
 */
xstd_handle_t std_mdbcomm_start(void);

/**********************************************************/
/**
 * @brief 关闭 通用内存管理 的记录工作流程。
 */
xstd_void_t std_mdbcomm_stop(void);

/**********************************************************/
/**
 * @brief 获取 通用内存管理 的记录工作句柄。
 * @note  后续可按 xstd_mdebug_t 对象的操作接口获取其他信息。
 */
xstd_handle_t std_mdbcomm_handle(void);

/**********************************************************/
/**
 * @brief 获取当前 通用内存管理 中，所统计总共分配的内存大小。
 */
xstd_size_t std_mdbcomm_count(void);

////////////////////////////////////////////////////////////////////////////////

/**********************************************************/
/**
 * @brief 求 (2^N <= xst_value) 的 N 最大值。
 * @note  若 (0 == xst_value) 时，返回 XSTD_NAN_2PN 。
 */
xstd_size_t std_floor2pn(register xstd_size_t xst_value);

/**********************************************************/
/**
 * @brief 求 (2^N >= xst_value) 的 N 最小值。
 * @note  若 (xst_value > XSTD_MAX_2POW) 时，则返回 XSTD_NAN_2PN。
 */
xstd_size_t std_ceil2pn(register xstd_size_t xst_value);

/**********************************************************/
/**
 * @brief 求 (2^N <= xst_value) 的 2^N 最大值。
 */
xstd_size_t std_floor2pow(register xstd_size_t xst_value);

/**********************************************************/
/**
 * @brief 求 (2^N >= xst_value) 的 2^N 最小值。
 * @note  若 (xst_value >= XSTD_MAX_2POW) 时，则返回 XSTD_MAX_2POW。
 */
xstd_size_t std_ceil2pow(register xstd_size_t xst_value);

////////////////////////////////////////////////////////////////////////////////

#ifdef __cplusplus
}; // extern "C"
#endif // __cplusplus

////////////////////////////////////////////////////////////////////////////////

#endif // __STD_COMM_H__
